---
title: Models
sidebarTitle: Models
description: Enhance Stagehand with LLMs for optimal performance, cost, and reliability
---

Stagehand uses Large Language Models (LLMs) to understand web pages, plan actions, and interact with complex interfaces. The choice of LLM significantly impacts your automation's accuracy, speed, and cost.

<Card title="Model Evaluation" href="https://www.stagehand.dev/evals" icon="paper-plane">
Find more details about how to choose the right model on our Model Evaluation page.
</Card>

## Why LLM Choice Matters

- **Accuracy**: Better models provide more reliable element detection and action planning
- **Speed**: Faster models reduce automation latency
- **Cost**: Different providers offer varying pricing structures
- **Reliability**: Structured output support ensures consistent automation behavior

<Tip>
Find more details about how to choose the right model on our [Model Evaluation](https://www.stagehand.dev/evals) page.
</Tip>

<Warning>
Small models on **Ollama** struggle with consistent structured outputs. While technically supported, we don't recommend them for production Stagehand workflows.
</Warning>

## Environment Variables Setup

Set up your API keys before configuring Stagehand:

<CodeGroup>
```bash .env
# Choose one or more providers
OPENAI_API_KEY=your_openai_key_here
ANTHROPIC_API_KEY=your_anthropic_key_here
GOOGLE_API_KEY=your_google_key_here
GROQ_API_KEY=your_groq_key_here
```
</CodeGroup>

## Supported Providers

Stagehand supports major LLM providers with structured output capabilities:

### Production-Ready Providers

| Provider | Best Models | Strengths | Use Case |
|----------|-------------|-----------|----------|
| **OpenAI** | `gpt-4.1`, `gpt-4.1-mini` | High accuracy, reliable | Production, complex sites |
| **Anthropic** | `claude-3-7-sonnet-latest` | Excellent reasoning | Complex automation tasks |
| **Google** | `gemini-2.5-flash`, `gemini-2.5-pro` | Fast, cost-effective | High-volume automation |

### Additional Providers

<Expandable title="More Providers">
- **Groq** - `llama-3.3-70b-versatile` (Good for speed critical applications)
- **xAI** - `grok-beta` (Good for complex reasoning)
- **Azure** - Enterprise OpenAI deployment
- **Cerebras** - High-speed inference
- **TogetherAI** - Open-source models
- **Mistral** - `mixtral-8x7b-32768` (European option)
- **DeepSeek** - Cost-effective alternative
- **Perplexity** - Real-time web data
- **Ollama** - Local deployment (limited accuracy)
- **Run any model included in AI SDK** - Find supported models in the [Vercel AI SDK](https://sdk.vercel.ai/providers/ai-sdk-providers) (Follow the guide 
     [here](#vercel-ai-sdk) to get started.)
</Expandable>

## Basic Configuration

### Model Name Format

Stagehand uses the format `provider/model-name` for model specification.

**Examples:**
- OpenAI: `openai/gpt-4.1`
- Anthropic: `anthropic/claude-3-7-sonnet-latest`
- Google: `google/gemini-2.5-flash` (Recommended)

### Quick Start Examples

<Tabs>
<Tab title="Google (Recommended)">
<CodeGroup>
```typescript TypeScript
import { Stagehand } from "@browserbasehq/stagehand";

const stagehand = new Stagehand({
  modelName: "google/gemini-2.5-flash",
  modelClientOptions: {
    apiKey: process.env.GOOGLE_API_KEY,
  },
});
```
```python Python
import os
from stagehand import Stagehand

stagehand = Stagehand(
    model_name="google/gemini-2.5-flash",
    model_api_key=os.getenv("GOOGLE_API_KEY")
)
```
</CodeGroup>
</Tab>
<Tab title="OpenAI">
<CodeGroup>
```typescript TypeScript
import { Stagehand } from "@browserbasehq/stagehand";

const stagehand = new Stagehand({
  modelName: "openai/gpt-4.1",
  modelClientOptions: {
    apiKey: process.env.OPENAI_API_KEY,
  },
});
```
```python Python
import os
from stagehand import Stagehand

stagehand = Stagehand(
    model_name="openai/gpt-4.1",
    model_api_key=os.getenv("OPENAI_API_KEY")
)
```
</CodeGroup>
</Tab>

<Tab title="Anthropic">
<CodeGroup>
```typescript TypeScript
import { Stagehand } from "@browserbasehq/stagehand";

const stagehand = new Stagehand({
  modelName: "anthropic/claude-3-7-sonnet-latest",
  modelClientOptions: {
    apiKey: process.env.ANTHROPIC_API_KEY,
  },
});
```
```python Python
import os
from stagehand import Stagehand

stagehand = Stagehand(
    model_name="anthropic/claude-3-7-sonnet-latest",
    model_api_key=os.getenv("ANTHROPIC_API_KEY")
)
```
</CodeGroup>
</Tab>
</Tabs>

## Custom LLM Integration

<Note>
Only [LiteLLM compatible providers](https://docs.litellm.ai/docs/providers) are available in Python. Some may require extra setup.
</Note>

Integrate any LLM with Stagehand using custom clients. The only requirement is **structured output support** for consistent automation behavior.

### Vercel AI SDK
The [Vercel AI SDK](https://sdk.vercel.ai/providers/ai-sdk-providers) is a popular library for interacting with LLMs. You can use any of the providers supported by the Vercel AI SDK to create a client for your model, **as long as they support structured outputs**.

Vercel AI SDK supports providers for OpenAI, Anthropic, and Google, along with support for **Amazon Bedrock** and **Azure OpenAI**. For a full list, see the [Vercel AI SDK providers page](https://sdk.vercel.ai/providers/ai-sdk-providers).

To get started, you'll need to install the `ai` package (version 4) and the provider you want to use (version 1 - both need to be compatible with LanguageModelV1). For example, to use Amazon Bedrock, you'll need to install the `@ai-sdk/amazon-bedrock` package.

You'll also need to import the [Vercel AI SDK external client](https://github.com/browserbase/stagehand/blob/main/lib/llm/aisdk.ts) through Stagehand to create a client for your model.

<Tabs>
	<Tab title="npm">
	```bash
	npm install ai@4 @ai-sdk/amazon-bedrock@1
	```
	</Tab>

	<Tab title="pnpm">
	```bash
	pnpm install ai@4 @ai-sdk/amazon-bedrock@1
	```
	</Tab>

	<Tab title="yarn">
	```bash
	yarn add ai@4 @ai-sdk/amazon-bedrock@1
	```
	</Tab>
</Tabs>

<Note>
The `AISdkClient` is not yet available via the Stagehand npm package. For now, install Stagehand as a git repository to access the `AISdkClient` (this will be included in the npm package in an upcoming release).
</Note>

<Tabs>
	<Tab title="npm">
	```bash
	npm install @browserbasehq/stagehand@git+https://github.com/browserbase/stagehand.git
	```
	</Tab>

	<Tab title="pnpm">
	```bash
	pnpm install @browserbasehq/stagehand@git+https://github.com/browserbase/stagehand.git
	```
	</Tab>

	<Tab title="yarn">
	```bash
	yarn add @browserbasehq/stagehand@git+https://github.com/browserbase/stagehand.git
	```
	</Tab>
</Tabs>

```ts
// Install/import the provider you want to use.
// For example, to use Azure OpenAI, import { createAzure } from '@ai-sdk/azure';
import { bedrock } from "@ai-sdk/amazon-bedrock";
// @ts-ignore
import { AISdkClient } from "@browserbasehq/stagehand";

const stagehand = new Stagehand({
  llmClient: new AISdkClient({
	model: bedrock("anthropic.claude-3-7-sonnet-20250219-v1:0"),
  }),
});
```

## Troubleshooting

### Common Issues

<AccordionGroup>
<Accordion title="Model doesn't support structured outputs">
**Error**: `Model does not support structured outputs`

**Solution**:
Use models that support function calling/structured outputs. The minimum requirements are:

- Model must support JSON/structured outputs
- Model must have strong reasoning capabilities
- Model must be able to handle complex instructions

For each provider, use their latest models that meet these requirements. Some examples:

- **OpenAI**: GPT-4 series or newer
- **Anthropic**: Claude 3 series or newer 
- **Google**: Gemini 2 series or newer
- **Other providers**: Latest models with structured output support

**Note**: Avoid base language models without structured output capabilities or fine-tuning for instruction following. When in doubt, check our [Model Evaluation](https://www.stagehand.dev/evals) page for up-to-date recommendations.
</Accordion>

<Accordion title="Authentication errors">
**Error**: `Invalid API key` or `Unauthorized`

**Solution**:
- Verify your environment variables are set correctly
- Check API key permissions and quotas
- Ensure you're using the correct API key for the provider
- For Anthropic, make sure you have access to the Claude API
</Accordion>

<Accordion title="Inconsistent automation results">
**Symptoms**: Actions work sometimes but fail other times

**Causes & Solutions**:
- **Weak models**: Use more capable models - check our [Model Evaluation](https://www.stagehand.dev/evals) page for current recommendations
- **High temperature**: Set temperature to 0 for deterministic outputs
- **Complex pages**: Switch to models with higher accuracy scores on our [Model Evaluation](https://www.stagehand.dev/evals) page
- **Rate limits**: Implement retry logic with exponential backoff
- **Context limits**: Reduce page complexity or use models with larger context windows
- **Prompt clarity**: Ensure your automation instructions are clear and specific
</Accordion>

<Accordion title="Slow performance">
**Issue**: Automation takes too long to respond

**Solutions**:
- **Use fast models**: Choose models optimized for speed
  - Any model with < 1s response time
  - Models with "fast" or "flash" variants
- **Optimize settings**: 
  - Use `verbose: 0` to minimize token usage
  - Set temperature to 0 for fastest processing
  - Keep max tokens as low as possible
- **Consider local deployment**: Local models can provide lowest latency
- **Batch operations**: Group multiple actions when possible
</Accordion>

<Accordion title="High costs">
**Issue**: LLM usage costs are too high

**Cost Optimization Strategies**:
1. **Switch to cost-effective models**: 
   - Check our [Model Evaluation](https://www.stagehand.dev/evals) page for current cost-performance benchmarks
   - Choose models with lower cost per token that still meet accuracy requirements
   - Consider models optimized for speed to reduce total runtime costs
2. **Optimize token usage**: 
   - Set `verbose: 0` to reduce logging overhead
   - Use concise prompts and limit response length
3. **Smart model selection**: Start with cheaper models, fallback to premium ones only when needed
4. **Cache responses**: Implement LLM response caching for repeated automation patterns
5. **Monitor usage**: Set up billing alerts and track costs per automation run
6. **Batch processing**: Process multiple similar tasks together
</Accordion>
</AccordionGroup>

### Next Steps
<CardGroup cols={2}>
<Card title="Choose Models" href="https://www.stagehand.dev/evals" icon="robot">
  See our Model Evaluation page
</Card>

<Card title="Test Models" href="/configuration/evals" icon="flask-vial">
  Evaluate performance on your specific use cases in our Model Evaluation guide
</Card>

<Card title="Track Costs" href="/configuration/observability" icon="chart-line">
  Monitor token usage and set alerts using our Observability tools
</Card>

<Card title="Cache Results" href="/best-practices/caching" icon="database">
  Store successful patterns using our Caching Guide
</Card>
</CardGroup>